Shareware Grab Bag

home *** CD-ROM | disk | FTP | other *** search

/ Shareware Grab Bag / Shareware Grab Bag.iso / 090 / cmln0686.arc / PCTMK.DOC < prev next >

Wrap

Text File | 1986-03-31 | 24KB | 719 lines

PCTMK A tool for program development G. W. Glasscock 15617 S. E. Fairwood Blvd. Renton, Wa. 98058 (206) 271-0638 Version 1.0 Copyright (c) 1986, G. W. Glasscock, All rights reserved. DISCLAIMER The author has taken due care in preparing this manual and accompanying program to ensure it operates as described. However, the author makes no expressed or implied warranty of any kind with regard to this program or the documentation in the manual. Under no circumstances shall the author be liable for incidental or consequential damages arising from the use or inability to use this program. è Page 1 INTRODUCTION PCTMK is a tool for conveniently building a program or a set of programs ensuring that the current version of a program reflects all changes made to any of the source files comprising that program. It accomplishes this task efficiently by compiling only those source files which have been modified. A command entered at the DOS command prompt is used to invoke PCTMK and provide the name of the target file to be constructed. The user supplies the detailed knowledge needed to construct the target file through rules which he places in a "makefile". If the modular approach to program development is used, it is easy to forget which source files have been modified and which source files make up a particular program. Since the user of PCTMK must create a "makefile", he has conveniently documented the steps necessary to build his program. PCTMK provides programmers who use PCDOS [1] and MS-DOS [2] an introduction to the capabilities of "make" which was developed by S. I. Feldman of Bell Laboratories for the UNIX [3] operating system. PCTMK is intended for use with version 2.0 and later releases of PCDOS or MS-DOS. PCTMK will work with most compilers and assemblers which run on these operating systems. Although PCTMK provides the basic capabilities needed for a "make" program, it is missing several advanced features useful in a complete "make" program. PCMK, a superset of PCTMK, provides these useful advanced features for only $21.00. Wild card character expansion Full path name support User defined macros Access to DOS environment via macros Access to internally generated macros Built-in rules defined by the user Printed manual with examples (40 pages) 1. PCDOS is a Trademark of International Business Machines 2. MS-DOS is a Trademark of Microsoft Inc. 3. UNIX is a Trademark of Bell Laboratories Page 2 BASIC OPERATION The basic function of PCTMK is to produce a target file which is current or up-to-date. It accomplishes this by automatically executing all commands necessary to produce the updated target file. A target file is defined as "current" if its date and time are more recent than any file on which it depends. PCTMK determines what needs to be done by examining the "make- file". This "makefile" contains user supplied rules. These rules contain a list of files that a target depends upon and a list of the commands necessary to create the target file. The date and time of a file's last modification is obtained from DOS. This date and time must be accurate if PCTMK is to operate correctly. As an illustration, suppose a program called "mypgm.exe" is built from three assembly language files: "f1.asm", "f2.asm", and "f3.asm". Also, assume that a file of macro definitions "mdefs.mac" is "included" in the assembly language files "f2.asm" and "f3.asm". Using only the basic capabilities of PCTMK, the four rules shown below describe the "makefile" required to build the program "mypgm.exe". mypgm.exe : f1.obj f2.obj f3.obj link f1.obj f2.obj f3.obj, mypgm.exe, NUL; f1.obj : f1.asm masm f1.asm; f2.obj : f2.asm mdefs.mac masm f2.asm; f3.obj : f3.asm mdefs.mac masm f3.asm; The first rule states that "mypgm.exe" depends on "f1.obj", "f2.obj", and "f3.obj". The second line of this rule is the DOS command or program to run if "mypgm.exe" is out of date with any of the files on which it it depends. The second rule states that "f1.obj" depends upon "f1.asm" and provides a command to create "f1.obj". Likewise, the third rule states that "f2.obj" depends on "f2.asm" and "mdefs.mac". The second line of this rule is the DOS command which will create an updated "f2.obj". The fourth rule is similar to the third rule. If these four rules are placed in a file named "MAKEFILE", the command PCTMK Page 3 is sufficient to cause "mypgm.exe" to be recreated after a change had been made to any of the source files, "f1.asm", "f2.asm", "f3.asm", or "mdef.mac". Let's assume that after running "mypgm", it is determined that a modification to the file "f2.asm" is necessary to correct a problem. After making this modification, PCTMK is executed. From the four rules in "MAKEFILE" and the date and times of the target and dependency files, PCTMK discovers that "f2.asm" has been modified and executes the command associated with rule 3. The command associated with rule 1 will then be executed because "f2.obj" is now out of date. The commands associated with rules 2 or 4 are not executed because the targets in these rules are current with their dependency files. Page 4 MAKEFILE SYNTAX The overall syntax of a "makefile" is relatively simple. It contains lines of ASCII text by which the user can construct rules. A rule is an entry in the "makefile" which states depend- ency condition(s). It also defines actions to be taken should that condition be met. Blank lines are allowed between rules. The sharp "#" character is used to start a comment. When a sharp "#" is found, the line is effectively ended because the sharp and all characters following the sharp up to the end-of-line are ignored. If it is necessary to use a sharp in a rule, it can be "escaped"; the sequence "\#" is replaced by a sharp and does not signify the start of a comment. Non-comment lines may be continued by placing a backslash "\" character at the end of the line. In this case, the backslash followed by an end-of-line is ignored so that the first character of the next line immediately follows the character which preceded the backslash. To define a rule within the "makefile", use the following syntax: target : [dependent ... ] [; command] [(tab) command] ... Items inside brackets are optional and may be omitted. The appearance of three dots "..." means that the previous item may be repeated. Targets and dependents are strings of letters, digits, and special characters delimited by white space. White space must both precede and follow the colon. White space is defined as one or more blanks or tab characters. Targets and dependents can appear in more than one rule. Because targets and dependents refer to DOS file names which may or may not exist, you would be wise to restrict your use of special characters to those which can be used in valid DOS file names. A command is any string of characters terminating with an unescaped sharp "#" or the end-of-line sequence. Usually com- mands appear on separate lines which begin with a tab character. However, one command may be placed at the end of a target/ dependency line if it is preceded by a semicolon. The commands of a rule are executed in the order of appearance provided at least one of the dependents is more recent than the target. The first string in a DOS command line identifies the file/ command to be executed. Three types of files, ".COM", ".EXE", and ".BAT", as well as commands which are internal to the DOS command line processor, can be run under DOS. PCTMK handles all Page 5 of these commands. It is not necessary to provide the suffix of the command to be run. The syntax of the command should conform to DOS conventions, but depends to a large extent upon the command being executed. A comment may be placed at the end of a target or command line by using the sharp "#" to signal the start of the comment. Both target lines and command lines that do not end with a comment may be continued. Page 6 PCTMK COMMAND pctmk [-f makefile] [-s] [-i] [-n] [names] Any or all of the command line parameters may be omitted. The sequence in which parameters are entered has no significance for their meaning. Command line parameters are of two types: options and target names. The case of the characters on the command line is not significant. Options The four PCTMK options are: -f "makefile" is the name of a file which contains the rules that you want PCTMK to process. If this option is omitted, PCTMK uses the file "MAKEFILE" in the current directory. -s specifies that PCTMK call the system's command processor "COMMAND.COM" to execute all commands. -i requests that error codes returned by commands be ignored. Normally, PCTMK aborts when a command it executes generates an error return. When this option is present, it will continue processing. This option is useful when working with commands that set the "exit" code incorrectly. -n requests that PCTMK only print the commands that would be executed but not execute them. This option allows you to see what commands PCTMK would issue without actually executing them. Target Names [names] For each target name present on the command line, PCTMK attempts to create an updated version of that target. If no targets are present on the command line, the first target found in the "makefile" will be updated. Page 7 OPERATIONAL DETAILS The information provided in this section will help you understand the operation of PCTMK so that you can better take advantage of this tool. Command Execution PCTMK provides two options for executing or running commands. Direct execution is the preferable method because PCTMK can access the exit code of the DOS command it executes and halt when that command (i.e. a compiler or assembler) detects errors. Of course, access to the exit code is useless unless it is set accurately by the command being executed. You may provide the full path name for a file to be executed. If only the command name is given, PCTMK tries to locate a command by first looking in the current directory, then in the directories identified by the DOS environment variable, PATH. The full path name is necessary to execute a command which is not in the current directory or in a directory identified by the environment PATH variable. Commands can also be executed by first calling the DOS command line interpreter which will then execute the command. There are three reasons PCTMK uses this method for executing commands. Since some commands are internal to the DOS command processor or have special syntactical conventions, they must be executed by the DOS command line processor. Appendix A contains a list of the commands PCTMK always executes via the DOS command line processor. PCTMK does not itself handle redirection of input, redirection of output, or pipes. If a command line contains any of the characters "<", ">", or "|", that command line is executed via the DOS command line processor. Any command which has a ".BAT" suffix is executed via the DOS command line processor. The problem with executing commands via the DOS command processor is that the exit code of the command is not available to PCTMK. PCTMK WILL CONTINUE NORMALLY WHEN A COMMAND EXECUTED BY THE DOS COMMAND LINE INTERPRETER ABORTS BECAUSE PCTMK IS NOT INFORMED OF THIS ABNORMAL CONDITION. By using the "-s" option, you can force PCTMK to call the DOS command line processor to execute all commands. Size of Commands DOS restricts the parameter portion of a command line to 126 characters. If the command is to be executed via the command line processor, the complete command may not exceed 123 characters. Several techniques have been developed to cope with this limit. Some of the DOS commands, (i.e. copy and backup) Page 8 avoid this problem by expanding wild card characters as a part of the command. "LINK" allows parameters to be input from a file as an alternative to the DOS command line. For some commands, simply running the command multiple times will avoid this limit. PCTMK helps cope with this situation by allowing one target to appear in multiple rules. For each rule the commands associated with that rule are executed if the target is out of date with any of the dependencies of that rule. Support of Path Names PCTMK allows all file names to include a full path qualifier. However, some assemblers and compilers do not allow file names which include a path. This is universally true for compilers and assemblers which were produced before DOS 2.0 was available. Even the DOS 2.0 command processor has restrictions on the use of file names which contain a path prefix. Lower Case vs Upper Case Where possible PCTMK maintains the distinction between upper and lower case letters. That is the string "abcd" is not identical to the string "ABCD". However, PCTMK must deal with DOS which converts the lower case letters to upper case in file names. As a result, lower case letters in target names are converted to uppercase. Page 9 EXAMPLE OF USAGE The previous sections have described the basic operation of PCTMK, the syntax of the "makefile", and the command line used to invoke PCTMK. This section presents an example using PCTMK and a product from C Ware. The "makefile" illustrated here uses an assembler and a "C" compiler. This "makefile" happens to be the one used to develop PCTMK. # Rule 1 pctmk.exe : pcmk.o parser.o builtin.o ffind.o fetenv.o bind pcmk.o parser.o builtin.o ffind.o fetenv.o a:exec.o \ -opctmk -p -s4000 # Rule 2 pcmk.o : pcmk.c defs.h c88 pcmk.c # Rule 3 parser.o : parser.c defs.h c88.exe parser.c # Rule 4 builtin.o : builtin.c defs.h c88 builtin.c # Rule 5 ffind.o : ffind.a asm88 ffind.a # Rule 6 fetenv.o : fetenv.a asm88 fetenv.a Rule 1 describes how to build "pctmk.exe". Because this is the first target in the "makefile", it is chosen whenever a target is omitted from the PCTMK command line. The dependency part of this rule list the five (5) object files on which "pctmk.exe" depends that are subject to change. The second line of this rule starts with a tab and is the command to run if one or more of the dependencies are out-of-date with "pctmk.exe". This line is continued because the backslash "\" at the end of the line immediately precedes the end-of-line sequence. When this command is executed PCTMK looks for "bind" in the current directory, then the directories specified by the environment variable PATH. The parameters for this command are the object files on which "pctmk.exe" depends, "a:exec.o" and the three option flags. The "-o" option supplies the name for the output of "bind". The file "a:exec.o", which is part of the compiler package, is needed to construct "pctmk.exe". It is not Page 10 necessary to include this file in the dependency list since it does not change. Before deciding to execute the command in rule 1, PCTMK must ensure that all of the dependents are also current. To do this, PCTMK attempts to "make" each of the dependents. It will find rules for each of these sub-targets. Rule 2 states that "pcmk.o" depends upon "pcmk.c" and "defs.h". If either of the files "pcmk.o" or "defs.h" are out-of date with "pcmk.o", the command which is the second line of rule 2 will be run to re-build "pcmk.o". Rules 3 and 4 are similar to rule 2. Note that the full name of the compiler, "c88.exe", is present in the command portion of rule 3. Rule 5 states that "ffind.o" depends upon "ffind.a". If "ffind.o" is out-of-date with "ffind.a" the command show in the second line of this rule will be executed. Rule 6 is similar to rule 5. You should be aware that PCTMK will try to "make" all of the file names which it encounters in a dependency list. Even the source files: "pcmk.c", "parser.c", "builtin.c", "ffind.a", "fetenv.a", and "defs.h". The attempt to "make" these source files will not succeed because there are no rules present that create these source files. Because of this feature, PCTMK will work in environments where program generators and precompilers are used. Appendix A Page 11 DOS COMMANDS The commands listed below are always executed via the DOS command processor. The exit code is not available to PCMK when the DOS command processor is called to execute a command. backup break chdir cd chkdsk cls comp copy ctty date del erase dir echo for if mkdir md more pause print ren rename restore rmdir rd sort time type ver verify vol Appendix B Page 12 DISTRIBUTION OF PCTMK PCTMK and its document is available at no cost to those who want to use it. Please help distribute this software by copying both the program and the electronic form of the manual for anyone who may want to use this program. The only restriction on copying this software is that the electronic form of the manual be copied along with the program, and that neither the program nor the manual be modified in any way. I have placed PCTMK on several computer bulletin boards and I hope it will spread to additional bulletin boards. PCTMK is not directly available from the author. Copies of PCTMK must be obtained from either a bulletin board or a friend. My motivation for making this program available at no cost is to help market PCMK which is a superset of PCTMK and provides the user many useful and convenient features. - Wild card character expansion - Full path name support - User defined macros - Access to DOS environment via macros - Access to internally generated macros - Built-in rules defined by the user - Printed manual with examples (40 pages) A copy of PCMK and its 40 page printed manual are available from the author for $21.00. A check or money order for the full amount of the order must accompany all orders. Washington state residents include 8.1% sales tax. G. W. Glasscock 15617 S. E. Fairwood Blvd. Renton, Wa. 98058 (206) 271-0638 Because of the low cost of this product, I will not be able to return your long distance telephone calls. However, I am willing to talk with you if you pay for the call. I am available most evenings 6:00 PM to 9:00 PM PST. I will answer all mail that I receive concerning PCMK or PCTMK.